home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / perl / 5.10.0 / CPANPLUS / Shell / Default / Plugins / HOWTO.pod < prev    next >
Encoding:
Text File  |  2009-06-26  |  3.8 KB  |  137 lines
  1. =head1 NAME
  2.  
  3. CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write your own plugins
  4.  
  5. =head1 SYNOPSIS
  6.  
  7.     package CPANPLUS::Shell::Default::Plugins::MyPlugin;
  8.     
  9.     ### return command => method mapping
  10.     sub plugins { ( myplugin1 => 'mp1', myplugin2 => 'mp2' ) }
  11.     
  12.     ### method called when the command '/myplugin1' is issued
  13.     sub mp1 { .... }
  14.  
  15.     ### method called when the command '/? myplugin1' is issued
  16.     sub mp1_help { return "Help Text" }
  17.     
  18. =head1 DESCRIPTION
  19.  
  20. This pod text explains how to write your own plugins for 
  21. C<CPANPLUS::Shell::Default>. 
  22.  
  23. =head1 HOWTO
  24.  
  25. =head2 Registering Plugin Modules
  26.  
  27. Plugins are detected by using C<Module::Pluggable>. Every module in
  28. the C<CPANPLUS::Shell::Default::Plugins::*> namespace is considered a
  29. plugin, and is attempted to be loaded.
  30.  
  31. Therefor, any plugin must be declared in that namespace, in a corresponding
  32. C<.pm> file.
  33.  
  34. =head2 Registering Plugin Commands
  35.  
  36. To register any plugin commands, a list of key value pairs must be returned
  37. by a C<plugins> method in your package. The keys are the commands you wish 
  38. to register, the values are the methods in the plugin package you wish to have
  39. called when the command is issued.
  40.  
  41. For example, a simple 'Hello, World!' plugin:
  42.  
  43.     package CPANPLUS::Shell::Default::Plugins::HW;
  44.     
  45.     sub plugins { return ( helloworld => 'hw' ) };
  46.     
  47.     sub hw { print "Hello, world!\n" }
  48.     
  49. When the user in the default shell now issues the C</helloworld> command,
  50. this command will be dispatched to the plugin, and it's C<hw> method will
  51. be called
  52.  
  53. =head2 Registering Plugin Help
  54.  
  55. To provide usage information for your plugin, the user of the default shell
  56. can type C</? PLUGIN_COMMAND>. In that case, the function C<PLUGIN_COMMAND_help>
  57. will be called in your plugin package.
  58.  
  59. For example, extending the above example, when a user calls C</? helloworld>,
  60. the function C<hw_help> will be called, which might look like this:
  61.  
  62.     sub hw_help { "    /helloworld      # prints "Hello, world!\n" }
  63.     
  64. If you dont provide a corresponding _help function to your commands, the
  65. default shell will handle it gracefully, but the user will be stuck without
  66. usage information on your commands, so it's considered undesirable to omit
  67. the help functions.
  68.  
  69. =head2 Arguments to Plugin Commands
  70.  
  71. Any plugin function will receive the following arguments when called, which
  72. are all positional:
  73.  
  74. =over 4
  75.  
  76. =item Classname -- The name of your plugin class
  77.  
  78. =item Shell     -- The CPANPLUS::Shell::Default object
  79.  
  80. =item Backend   -- The CPANPLUS::Backend object
  81.  
  82. =item Command   -- The command issued by the user
  83.  
  84. =item Input     -- The input string from the user
  85.  
  86. =item Options   -- A hashref of options provided by the user
  87.  
  88. =back
  89.  
  90. For example, the following command:
  91.  
  92.     /helloworld bob --nofoo --bar=2 joe
  93.     
  94. Would yield the following arguments:    
  95.  
  96.     sub hw {
  97.         my $class   = shift;    # CPANPLUS::Shell::Default::Plugins::HW
  98.         my $shell   = shift;    # CPANPLUS::Shell::Default object
  99.         my $cb      = shift;    # CPANPLUS::Backend object
  100.         my $cmd     = shift;    # 'helloworld'
  101.         my $input   = shift;    # 'bob joe'
  102.         my $opts    = shift;    # { foo => 0, bar => 2 }
  103.  
  104.         ....
  105.     }
  106.  
  107.  
  108. =head1 BUG REPORTS
  109.  
  110. Please report bugs or other issues to E<lt>bug-cpanplus@rt.cpan.org<gt>.
  111.  
  112. =head1 AUTHOR
  113.  
  114. This module by Jos Boumans E<lt>kane@cpan.orgE<gt>.
  115.  
  116. =head1 COPYRIGHT
  117.  
  118. The CPAN++ interface (of which this module is a part of) is copyright (c) 
  119. 2001 - 2007, Jos Boumans E<lt>kane@cpan.orgE<gt>. All rights reserved.
  120.  
  121. This library is free software; you may redistribute and/or modify it 
  122. under the same terms as Perl itself.
  123.  
  124. =head1 SEE ALSO
  125.  
  126. L<CPANPLUS::Shell::Default>, L<CPANPLUS::Shell>, L<cpanp>
  127.  
  128. =cut
  129.  
  130. # Local variables:
  131. # c-indentation-style: bsd
  132. # c-basic-offset: 4
  133. # indent-tabs-mode: nil
  134. # End:
  135. # vim: expandtab shiftwidth=4:
  136.  
  137.